Collection and Drop Off API

(0 reviews)

Drop Off Addresses

Resource URL

UAT:

https://api.uat.nzpost.co.nz/collectionaddress/v1/dropoffs/all
https://api.uat.nzpost.co.nz/collectionaddress/v1/dropoffs/{address_id}

Production:

https://api.nzpost.co.nz/collectionaddress/v1/dropoffs/all
https://api.nzpost.co.nz/collectionaddress/v1/dropoffs/{address_id}

Resource Information

Attribute	Detail
Response Format	JSON
Requires Authentication	Yes
Rate Limited	15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Resource Description

1. The all drop off resource has no parameters required to retrieve a list of all of the drop off points.

2. Another drop off resource uses an address_id and param of count & max_distance to retrieve address details for the address_id and a list of nearby drop off points. The address_Id can be obtained using the "Search for Address" resource in the ParcelAddress API. Notes: Please make “ParcelAddress” a link to the ParcelAddress 2.0 page in the developer portal.

Please note that all request parameters should be in lower case.

Request Parameters

The resource of the "all drop off addresses" has no parameters required.

The following list of the request parameters for the "drop off parcel addresses" resource.

Field Name	Description	Mandatory	Example
address_id	NZ Post address identifier as URI parameter	Yes	12345
count	Number of parcel drop off location address records to be returned(min:1,default:10)	No	12
max_distance	Locations returned are within the max distance radius, measured in kilometres. (default:5)	No	10

Sample Request

https://api.nzpost.co.nz/collectionaddress/v1/dropoffs/all
https://api.nzpost.co.nz/collectionaddress/v1/dropoffs/12345?count=3&max_distance=10

Response Parameters

All Drop Off Address Object

The following lists the required fields in the Get all Drop Off Address Detail response message:

Field Name	Description	Mandatory	Example
success	Returns if request is successful	Yes	True
drop_off_locations	Address object with address details	Y if success = true	JSON Object
message_id	The envent message mark	Yes	a2d13150-5f38-11ee-b010-02d78cbdb7cd	the

Drop Off Object

Field Name	Description	Mandatory	Example
company_name	Name of the company hosting the collection point	Yes	Dunedin CourierPost Depot
lat	Longitude of the collection Point	Yes	-45.888675
lng	Longitude of the collection Point	Yes	170.503033
phone	Contact phone number for the collection point	Yes	0800 268 7437
full_address	Human readable street address for the collection point	Yes	Strathallan Street, South Dunedin, Dunedin 9012
id	Location ID for the drop off point	Yes	99054
hours	Array listing the opening and closing hours of the collection point for each day of the week	Yes	JSON Object
address_details	The drop off location details	Yes	JSON Object
services	The drop off location's service scope	Yes	["post_a_parcel","pay_a_bill","send_a_letter"]
type	Service type of the drop off location	Yes	PostShop

Hours Array

The following lists the field in the hours object.

Field Name	Description	Mandatory	Example
day	Indicates the day of the week where 0 = Sunday through 6 = Saturday	Yes	2
open	Time of opening for day indicated in day parameter using 24 hour clock	No	08:30
close	Time of closing for day indicated in day parameter using 24 hour clock. If location not open, then parameter set to 'true'	Yes	18:00

Address_details Object

The following lists the field in the address_details object.

Field Name	Description	Mandatory	Example
address_line_1	Details of the street number and building name	Yes	5 Strathallan Street
suburb	The name of the suburb the address resides	Yes	South Dunedin
city	The city the address resides in	Yes	Dunedin
post_code	The postcode associated with the address	Yes	9012

Drop Off Search Object

The following lists the required fields in the Get the Nearby Drop Off Address Detail response message:

Field Name	Description	Mandatory	Example
success	Returns if the request is successful	Yes	True
address	Address object with address details	Y if success = true	JSON Object
message_id	The envent message mark	Yes	a2d13150-5f38-11ee-b010-02d78cbdb7cd

Address Object

Field Name	Description	Mandatory	Example
street_number	The street number of the address	Yes	71
street	The name of the street	Yes	Oregon
street_type	Type of the street	Yes	Street
suburb	The name of the suburb the address resides in	Yes	Ocean Grove
city	The name of the city the address resides in	Yes	Dunedin
is_rural_delivery	Determines if this is a rural or an urban address (true for rural)	Yes	false
postcode	The postcode associated with the address	Yes	9013
longitude	The GPS longitude coordinate if the data exists	Yes	170.552
latitude	The GPS latitude coordinate if the data exists	Yes	-45.9041
run_number	The run number that indicates which courier run will service this address	Yes	DCP025
depot_name	The name of the depot that services this address	Yes	Dunedin Depot
country	The name of the country the address resides	Yes	New Zealand
dpid	Delivery point identifier	Yes	54218
address_id	Location ID for the drop off point	Yes	12345
drop_off_locations	Contains array of post the parcel location objects. The number of objects will not exceed the ‘count’ value defined and the max distance will not exceed the ‘max_distance’ value defined.	Yes if success=true	JSON Object

Drop_off_locations Object

The following lists the fields in the locations object.

Field Name	Description	Mandatory	Example
company_name	Name of the company hosting the collection point	Yes	Dunedin CourierPost Depot
lat	Longitude of the collection Point	Yes	-45.888675
lng	Longitude of the collection Point	Yes	170.503033
phone	Contact phone number for the collection point	Yes	0800 268 7437
full_address	Human readable street address for the collection point	Yes	Strathallan Street, South Dunedin, Dunedin 9012
id	Location ID for the drop off point	Yes	99054
hours	Array listing the opening and closing hours of the collection point for each day of the week	Yes	JSON Object
distance_in_m	Distance between the address and drop off location	Yes	4159
address_details	The drop off location details	Yes	JSON Object
services	The drop off location's service scope	Yes	["post_a_parcel","pay_a_bill","send_a_letter"]
type	Service type of the drop off location	Yes	PostShop

Hours Array

The following lists the field in the hours object.

Field Name	Description	Mandatory	Example
day	Indicates the day of the week where 0 = Sunday through 6 = Saturday	Yes	2
open	Time of opening for day indicated in day parameter using 24 hour clock	No	08:30
close	Time of closing for day indicated in day parameter using 24 hour clock. If location not open, then parameter set to 'true'	Yes	18:00

Address_details Object

The following lists the field in the address_details object.

Field Name	Description	Mandatory	Example
address_line_1	Details of the street number and building name	Yes	5 Strathallan Street
suburb	The name of the suburb the address resides	Yes	South Dunedin
city	The city the address resides in	Yes	Dunedin
post_code	The postcode associated with the address	Yes	9012

Response Message - Collection and Drop Off API Response Message

Sample get all drop off request : https://api.nzpost.co.nz/collectionaddress/v1/dropoffs/all

Sample get all drop off success response:

  {
    "success": true,
    "drop_off_locations": [
        {
            "company_name": "NZ Post Shop Beachlands",
            "lat": -36.882536,
            "lng": 174.996944,
            "phone": "09 536 6118",
            "full_address": "Beachlands PostShop & Lotto, 38 Wakelin Road, Beachlands, Auckland 2018",
            "id": 58040,
            "hours": [
                {
                    "day": 0,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 1,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 2,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 3,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 4,
                    "open": "09:00",
                    "close": "17:00"
                },
                {
                    "day": 5,
                    "open": "09:00",
                    "close": "14:30"
                },
                {
                    "day": 6,
                    "closed": true
                }
            ],
            "address_details": {
                "address_line_1": "38 Wakelin Road",
                "suburb": "Beachlands",
                "city": "Auckland",
                "post_code": "2018"
            },
            "services": [
                "box_lobby",
                "post_a_parcel",
                "purchase_postage",
                "pay_a_bill",
                "counter_delivery",
                "post_a_letter_standard",
                "parcel_collection",
                "missed_parcel_collection_only",
                "send_a_parcel_in_nz",
                "send_a_parcel_overseas",
                "send_a_letter"
            ],
            "type": "PostShop"
        }, {...}, {...}
      ],
    "message_id": "a2d13150-5f38-11ee-b010-02d78cbdb7cd"
}

Sample get all drop off request : https://api.nzpost.co.nz/collectionaddress/v1/dropoffs/12345?count=3&max_distance=10

Sample drop off search success response:

  {
    "success": true,
    "address": {
        "street_number": 71,
        "street": "Oregon",
        "street_type": "Street",
        "suburb": "Ocean Grove",
        "city": "Dunedin",
        "is_rural_delivery": false,
        "gated_community_flag": false,
        "postcode": "9013",
        "longitude": 170.552,
        "latitude": -45.9041,
        "run_number": "DCP015",
        "depot_name": "Dunedin Depot",
        "country": "New Zealand",
        "dpid": 33837,
        "address_id": 12345,
        "drop_off_locations": [
            {
                "company_name": "NZ Post Dunedin Depot",
                "lat": -45.888675,
                "lng": 170.503033,
                "phone": "0800 268 7437",
                "full_address": "5 Strathallan Street, South Dunedin, Dunedin 9012",
                "id": 99054,
                "hours": [
                    {
                        "day": 0,
                        "open": "08:30",
                        "close": "18:00"
                    },
                    {
                        "day": 1,
                        "open": "08:30",
                        "close": "18:00"
                    },
                    {
                        "day": 2,
                        "open": "08:30",
                        "close": "18:00"
                    },
                    {
                        "day": 3,
                        "open": "08:30",
                        "close": "18:00"
                    },
                    {
                        "day": 4,
                        "open": "08:30",
                        "close": "18:00"
                    },
                    {
                        "day": 5,
                        "open": "09:00",
                        "close": "12:00"
                    },
                    {
                        "day": 6,
                        "closed": true
                    }
                ],
                "distance_in_m": 4159,
                "address_details": {
                    "address_line_1": "5 Strathallan Street",
                    "suburb": "South Dunedin",
                    "city": "Dunedin",
                    "post_code": "9012"
                },
                "services": [
                    "post_a_parcel",
                    "parcel_collection"
                ],
                "type": "Depot"
            }
            ]
    },
    "message_id": "019f04b0-5f38-11ee-b010-02d78cbdb7cd"
}

Response message- Collection and Drop Off API Error Response Message

Sample failure response:

 {
   "success": false,
   "errors": [ {
   "code": "40001",
   "message": "Bad Request",
   "details": "You may have entered invalid or missing input parameters,
   please consult the API documentation if in doubt." } ],
   "message_id": "4dd9d6d0-ab89-11e6-b31d-0692fd96189f"
 }

HTTP Status Codes

Note that some error messages are customized for the request, i.e. error code 400 usually will describe what is wrong with the request

Code	Message
200	Success
400	Bad Request
401	Unauthorized
403	Forbidden
404	Not Found
409	Invalid request
500	System unavailable

Error Codes

Code	Message
200001	Partial results returned,not all system(s) have responded
200002	All sources responded,data may be incomplete
400001	Parameter(s) missing
400002	Invalid parameter(s)
400003	Non mutually exclusive parameters detected
401001	Unauthorized access, please contact administrator
500001	General Exception
500002	System(s) offline